{/* Copyright 2020 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:@react-aria/button';
import typesDocs from 'docs:@react-types/shared/src/events.d.ts';
import {HeaderInfo, FunctionAPI, TypeLink, PageDescription} from '@react-spectrum/docs';
import {Keyboard} from '@react-spectrum/text';
import packageData from '@react-aria/button/package.json';

---
category: Buttons
keywords: [button, aria, form]
---

# useButton

<PageDescription>{docs.exports.useButton.description}</PageDescription>

<HeaderInfo
  packageData={packageData}
  componentNames={['useButton']}
  sourceData={[
    {type: 'W3C', url: 'https://www.w3.org/WAI/ARIA/apg/patterns/button/'}
  ]} />

## API

<FunctionAPI function={docs.exports.useButton} links={docs.links} />

## Features

On the surface, building a custom styled button seems simple. However, there are many
cross browser inconsistencies in interactions and accessibility features to consider.
`useButton` handles all of these interactions for you, so you can focus on the styling.

* Native HTML `<button>` support
* `<a>` and custom element type support via ARIA
* Mouse and touch event handling, and press state management
* Keyboard focus management and cross browser normalization
* Keyboard event support for <Keyboard>Space</Keyboard> and <Keyboard>Enter</Keyboard> keys

Read our [blog post](../blog/building-a-button-part-1) about the complexities of building buttons that work well across devices and interaction methods.

## Anatomy

Buttons consist of a clickable area usually containing a textual label or an icon
that users can click to perform an action. In addition, keyboard users may activate
buttons using the <Keyboard>Space</Keyboard> or <Keyboard>Enter</Keyboard> keys.

If a visual label is not provided (e.g. an icon only button), then an `aria-label` or
`aria-labelledby` prop must be passed to identify the button to assistive technology.

## Example

By default, `useButton` assumes that you are using it with a native `<button>` element.

```tsx example export=true
import {useButton} from '@react-aria/button';
import {useRef} from 'react';

function Button(props) {
  let ref = useRef<HTMLButtonElement | null>(null);
  let {buttonProps} = useButton(props, ref);
  let {children} = props;

  return (
    <button {...buttonProps} ref={ref}>
      {children}
    </button>
  );
}

<Button onPress={() => alert('Button pressed!')}>Test</Button>
```

## Custom element type

Sometimes you might need to use an element other than a native `<button>`. `useButton` supports
this via the `elementType` prop. When used with an element other than a native button, `useButton`
automatically applies the necessary ARIA roles and attributes to ensure that the element is exposed
to assistive technology as a button.

In addition, this example shows usage of the `isPressed` value returned by `useButton` to properly
style the button's active state. You could use the CSS `:active` pseudo class for this, but `isPressed`
properly handles when the user drags their pointer off of the button, along with keyboard support and better
touch screen support.

```tsx example
function Button(props) {
  let {children} = props;
  let ref = useRef<HTMLButtonElement | null>(null);
  let {buttonProps, isPressed} = useButton({
    ...props,
    elementType: 'span'
  }, ref);

  return (
    <span
      {...buttonProps}
      style={{
        background: isPressed ? 'darkgreen' : 'green',
        color: 'white',
        padding: 10,
        cursor: 'pointer',
        userSelect: 'none',
        WebkitUserSelect: 'none'
      }}
      ref={ref}>
      {children}
    </span>
  );
}

<Button onPress={() => alert('Button pressed!')}>Test</Button>
```

## Usage

The following examples show how to use the `Button` component created in the above example.

### Events

`useButton` supports user interactions via mouse, keyboard, and touch. You can handle all of these via the `onPress` prop. This is similar to the standard `onClick` event, but normalized to support all interaction methods equally. In addition, the `onPressStart`, `onPressEnd`, and `onPressChange` events are fired as the user interacts with the button.

Each of these handlers receives a <TypeLink links={typesDocs.links} type={typesDocs.exports.PressEvent} />, which exposes information about the target and the type of event that triggered the interaction. See [usePress](../usePress) for more details.

```tsx example
function Example() {
  let [pointerType, setPointerType] = React.useState(null);

  return (
    <>
      <Button
        onPressStart={e => setPointerType(e.pointerType)}
        onPressEnd={e => setPointerType(null)}>
        Press me
      </Button>
      <p>{pointerType ? `You are pressing the button with a ${pointerType}!` : 'Ready to be pressed.'}</p>
    </>
  )
}
```

### Disabled

A `Button` can be disabled using the `isDisabled` prop.

```tsx example
<Button isDisabled>Pin</Button>
```

